home *** CD-ROM | disk | FTP | other *** search
/ Power CD / Power CD ATARI-Rechner Lieben.iso / UTILITY / EASYFSEL / EASYFSEL.TXT < prev   
Encoding:
Text File  |  1989-04-05  |  8.0 KB  |  192 lines
  1. Andreas Papula
  2. Römerstraße 20
  3. 6200 Wiesbaden - Delkenheim
  4.  
  5. Dokumentation zu EASYFSEL.C Version 1.27
  6. Datum: 15.06.1992
  7.  
  8.  
  9. Jeder, der auf dem ATARI ST/STE/TT Programme unter GEM schreibt, 
  10. kam sicherlich schon einmal mit der Fileselectorbox und deren 
  11. Programmierung in Berührung.
  12. Schon die Funktion fsel_input ist nicht sonderlich leicht zu 
  13. handhaben, da man erst die Rückgabeparameter auswerten und dann 
  14. noch den vollständigen Zugriffspfad zusammenbasteln muß [1].
  15. Ab TOS 1.04 bzw. AES 1.4 gibt es dann noch die Version fsel_exinput, 
  16. der zusätzlich ein Titel übergeben wird. Man sollte also wenn 
  17. möglich diese Funktion benutzen, da man so den Anwender 
  18. informieren kann, was er mit der Fileselectorbox auswählen soll. 
  19. Ein gutes Beispiel für so einen Titel wäre z.B. "Bitte zu 
  20. öffnende Datei auswählen" oder so etwas ähnliches.
  21. Viele Programmierer wissen nun aber nicht, wie man in eigenen 
  22. Programmen überprüfen kann, ob fsel_exinput() überhaupt vorhanden 
  23. ist und verwendet werden darf.
  24. Zusätzlich zu dieser Problematik existiert noch der 'FSEL'-Cookie 
  25. des alternativen Fileselectors "Selectric" (Shareware), der 
  26. anzeigt, das unter jeder TOS- bzw. AES-Version fsel_exinput() 
  27. vorhanden ist.
  28.  
  29.  
  30. Die Routinen...
  31. ---------------
  32.  
  33. Ziel war es, eine kleine (aber feine) Routinensammlung zu 
  34. entwickeln, die den Programmierer dabei unterstützt, die 
  35. Fileselectorbox korrekt auf den Bildschirm zu bringen, inkl. 
  36. Abfrage des 'FSEL'-Cookies. Nun ja, EASYFSEL.C stellt nun genau 
  37. so eine Routinensammlung dar, die auch noch über einige weitere 
  38. Routinen, etwa Abfrage eines Cookies etc., verfügt.
  39. Doch zuerst möchte ich die eigentliche Hauptroutine vorstellen, 
  40. easy_fsel(). Der Funktionsprototyp (in der Datei EASYFSEL.H) 
  41. lautet wie folgt:
  42.  
  43. BOOLEAN easy_fsel(BYTE *pfad, BYTE *dateiname, BYTE *text);
  44.  
  45. pfad ist dabei ein Zeiger auf einen String, der den Pfad enthält, 
  46. mit dem fsel_input() bzw. fsel_exinput aufgerufen wird. Nach dem 
  47. Ende der Funktion enthält pfad dann den vom Benutzer ausgewählten 
  48. Pfad. Entsprechendes gilt für dateiname. text ist der Titel, der 
  49. bei fsel_exinput() erscheint.
  50. Der Rückgabewert der Funktion ist TRUE, wenn der Benutzer 'OK' 
  51. ausgewählt hat und kein Fehler aufgetreten ist; FALSE, wenn 
  52. 'ABBRUCH' ausgewählt wurde oder ein Fehler aufgetreten ist.
  53. Der neuen Datentyp BOOLEAN ist in EASYFSEL.H wie folgt definiert:
  54.  
  55. typedef enum
  56. {
  57.   FALSE,
  58.   TRUE
  59. } BOOLEAN;
  60.  
  61. Diesen Datentyp werden wird noch bei einigen Funktionen benutzen; 
  62. er ist ganz nützlich und Sie können ihn auch in eigenen 
  63. Funktionen verwenden.
  64. easy_fsel() geht nun wie folgt vor:
  65. Zuerst werden (logisch) die benutzten Variablen deklariert, dann 
  66. wird, wenn die AES-Version kleiner 0x0014 ist oder der 'FSEL'-
  67. Cookie nicht gefunden wurde, fsel_input aufgerufen, ansonsten 
  68. fsel_exinput(). Die Parameter dieser beiden Funktionen möchte ich 
  69. hier erklären, da diese für die Benutzung der Routinensammlung 
  70. unerheblich sind und zweitens in [1] sehr gut beschrieben sind.
  71. Die AES-Version steht im ersten Element des global-Feldes. Um an 
  72. das global-Feld heran zu kommen, muß man folgende Deklaration in 
  73. sein Programm aufnehmen:
  74.  
  75. extern GEMPARBLK _GemParBlk;
  76.  
  77. Damit wird eine Variable namens _GemParBlk vom Typ der Struktur 
  78. GEMPARBLK deklariert. Diese Variable wird vom Startup-Code des 
  79. PURE C-Compilers bereitgestellt. Achten Sie also darauf, wenn Sie 
  80. einen anderen Startup-Code als einen der drei  Originalen 
  81. verwenden, daß die von Ihnen favorisierte Version sich in diesem 
  82. Punkt genauso wie die Originale verhält! Auf global[] kann man 
  83. dann wie folgt zugreifen:
  84.  
  85. _GemParBlk.global()
  86.  
  87. Das Suchen des Cookies übernimmt eine universell einsetzbare 
  88. Routine namens get_cookie(), die besonders dazu geeignet ist, zu 
  89. überprüfen, ob ein Cookie vorhanden ist. Ich werde weiter unten 
  90. noch genauer auf get_cookie() eingehen, doch zunächst zurück zu 
  91. easy_fsel(): Nachdem also fsel_input() oder fsel_exinput() 
  92. aufgerufen worden sind, wird die Auswertung der Rückgabeparameter 
  93. vorgenommen. Wenn der gedrückte Knopf 'Abbruch' ist oder ein 
  94. fehler aufgetreten ist, wird FALSE zurückgegeben, ansonsten TRUE. 
  95. Die aufrufende Funktion findet nun in pfad und dateiname die vom 
  96. Benutzer gemachten Eingaben vor und kann diese nun per 
  97. build_filename() zu einem gültigen Zugriffspfad zusammensetzen.
  98. build_filename() ist in EASYFSEL.H wie folgt deklariert:
  99.  
  100. VOID build_filename(BYTE *dest, BYTE *pfad, BYTE *dateiname);
  101.  
  102. Übergeben wird ein Zeiger auf einen String, der den kompletten 
  103. Zugriffspfad nach Beendigung der Funktion enthält, ein Zeiger auf 
  104. den Pfad und ein Zeiger auf den Dateinamen, aus denen der 
  105. Zugriffspfad zusammengebastelt werden soll. Die Routine ist 
  106. eigentlich selbsterklärend, so daß ich auf eine Beschreibung der 
  107. Arbeitsweise hier verzichte.
  108.  
  109. Des weiteren befindet sich noch die Funktion exist() in der 
  110. Sammlung, mit der es möglich ist, festzustellen, ob eine Datei 
  111. existiert. der Prototyp sieht wie folgt aus:
  112.  
  113. BOOLEAN exist(const BYTE *dateiname);
  114.  
  115. Die Funktion tätigt einen Aufruf der Funktion Fsfirst() und gibt, 
  116. falls die Datei im Verzeichnis gefunden wurde, TRUE zurück, 
  117. anderfalls FALSE. Gesucht wird dabei nach Dateien, die die 
  118. Attribute 'READONLY', 'HIDDEN', 'SYSTEM' oder 'ARCHIVE' besitzen.
  119.  
  120. Auch die Funktion get_akt_path() ist sicherlich hilfreich; sie 
  121. liefert den aktuellen Pfad zusammen mit dem aktuellen Laufwerk, 
  122. z. B. "D:\PC\SOURCEN\GEM".
  123. Übergeben wird ihr ein Zeiger auf einen String, in dem der Pfad 
  124. dann stehen soll. Zurückgeliefert wird ein Zeiger auf eben diesen 
  125. String.
  126. Es werden Aufrufe der PURE C - Spezialfunktionen getcurdir() und 
  127. getdisk() getätigt und aus deren Ergebnissen wird dann der 
  128. aktuelle Pfad mit dem aktuellen Laufwerk zusammengebastelt.
  129. get_akt_path() ist in EASYFSEL.H wie folgt deklariert:
  130.  
  131. BYTE *get_akt_path(BYTE *path);
  132.  
  133.  
  134. Cookie gesucht
  135. --------------
  136. Nun kommen wir zur letzten Funktion, nämlich get_cookie(), die 
  137. ich weiter oben schon mal angesprochen habe. Ich möchte hier 
  138. allerdings nicht den prinziellen Aufbau des Cookiejar 
  139. wiederholen, dieser ist z.B. in [1] oder [2] erläutert.
  140. Zunächst wird im Supervisor.Modus ein Zeiger auf den Cookiejar 
  141. geholt. Wenn dort NULL steht, d.h. der Cookiejar leer ist, wird 
  142. FALSE zurückgegeben. Andernfalls wird der Cookiejar solange 
  143. durchlaufen, bist der gewünschte Cookie gefunden wird oder ein 
  144. NULL-Zeiger vorkommt, d.h. der Cookiejar komplett durchlaufen 
  145. wurde.
  146. Wenn der Cookie gefunden wurde, wird TRUE zurückgegeben und der 
  147. Wert des Cookies der übergebenen Variable cookie_value 
  148. zugewiesen. Wenn der Cookie nicht auffinderbar ist, wird FALSE 
  149. zurückgegeben. Jetzt noch schnell der Prototyp von get_cookie():
  150.  
  151. BOOLEAN get_cookie(BYTE *cookie_name, LONG *cookie_value);
  152.  
  153. Wenn Sie nun beispielsweise überprüfen wollen, ob der 'VSCR'-
  154. Cookie (wird von BigScreen2, SciLab GmbH, gesetzt) vorhanden ist, 
  155. können Sie also wie folgt vorgehen:
  156.  
  157. ...
  158. long cookie_value = 0;
  159.  
  160. if(get_cookie("VSRC", &cookie_value) == TRUE)
  161. {
  162.   /* Cookie gefunden, Wert steht in cookie_value */
  163.   ...
  164. }
  165. else
  166. {
  167.   ...
  168. }
  169.  
  170.  
  171. Was bleibt ?
  172. ------------
  173. ... ist eine Routinensammlung, die man, sofern man Programme 
  174. schreibt, die in irgendeiner Form mit Dateien zu tun haben, immer 
  175. wieder verwenden kann und einem viel Gehirnschmalz erspart. Bei 
  176. mir ist EASYFSEL.C nun schon einige Wochen im Einsatz und ich bin 
  177. wirklich froh, daß ich mir die Mühe gemacht habe und mir eine 
  178. wirklich universell einsetzbare Routinensammlung geschrieben 
  179. habe. Das Modulkonzept von PURE C mit der guten Unterstützung 
  180. durch den Projectmanager macht es einem wirklich leicht, modular 
  181. aufgebaute Programme zu entwickeln und Module zu schreiben, die 
  182. man immer wieder verwenden kann.
  183. Um in eigenen Programmen EASYFSEL.C verwenden zu können, müssen 
  184. Sie EASYFSEL.H mittels #include in Ihre Programme einfügen und in 
  185. die jeweilige Projectdatei EASYFSEL.C aufnehmen.
  186.  
  187. Literaturhinweise:
  188. [1] Jankowski, Reschke, Rabich: ATARI Profibuch ST/STE/TT, Sybex 1991
  189. [2] "STEE-Gebäck - Das Cookie-Jar-Prinzip", ST-Computer 10/90, Seite 151-153
  190.  
  191.  
  192.